StoryCam 开发叙事 · 第 1 章
PR Gate 与 Codex Hooks 工作流重构
本 session 围绕 StoryCam 的开发分支、PR 前质量门禁、Git hook 与 Codex hook 的职责边界展开，最终把 AI review 从 GitHub Action 方案收回到项目级 Codex hook，并精确到一次成功的 git push 后询问是否运行 PR gate。
本 Session 摘要
- 先把 StoryCam 的本地与 GitHub 默认开发分支切到
dev，确保后续提交默认围绕 dev 分支展开。 - 梳理了三层 PR Gate：本地确定性检查、Codex 三视角 review、GitHub CI 强制门禁。
- 确认单纯把
code-reviewer + security-auditor + test-engineer写进 hook 或 PR 模板不会“激活” AI review，只能作为提醒。 - 从 Git hook、Codex hook、GitHub Action 三种方案中反复取舍，最终放弃 GitHub Codex Action，回到项目级 Codex hooks。
- 最终实现了
PreToolUse+PostToolUse两阶段握手：只对 Codex 发起的同一次成功git push注入 PR gate 提醒。 - 保留普通 Git
pre-push作为确定性检查入口，AI review 仍需用户确认后运行。
时间线
“建立一个 dev 分支在本地和github，然后通过 gh cli 将 github 的默认分支改为 dev，就是保证每次提交都是 dev 分支”
Codex 检查当前分支、远端和 GitHub 默认分支，发现默认分支仍是
main，本地有未提交改动。随后创建本地 dev，推送到 origin/dev，并用 gh repo edit 将 GitHub 默认分支改为 dev。结果 / 影响：StoryCam 的 GitHub 默认分支改为
dev；本地 dev 追踪 origin/dev。Codex 明确提醒：GitHub 默认分支不会强制本地每次 commit 都在 dev，本地提交仍取决于当前分支。“之前做了这些skills 和 hooks 等设计，现在我在提交代码的时候并没有看到这些路程正常的工作？”
Codex 排查仓库配置，发现
docs/PR_REVIEW.md、scripts/pr-ready.sh、.githooks/pre-push 都存在，但 core.hooksPath 没有启用。也澄清了这套设计是 pre-push，不是 pre-commit，所以提交时不会触发。结果 / 影响：本地执行
git config core.hooksPath .githooks，让 StoryCam 的 Git pre-push hook 真正生效。根因不是流程缺失，而是 hook 文件存在但 Git 没有指向它。“code-reviewer + security-auditor + test-engineer 三路 review 不会自动唤起的原因是？是不是做成自动唤起会更好？”
Codex 解释：Git hook 只能运行本地脚本，不能天然唤起当前 Codex 会话里的 subagents。AI review 慢、依赖模型与网络、结果有概率波动，不适合成为每次 commit 或 push 的唯一阻塞机制。
结果 / 影响：形成原则：确定性检查自动化，AI review 由人明确确认。PR Gate 的角色从“硬阻塞 hook”调整为“人确认后运行的智能审查”。
“做 半自动：让 .githooks/pre-push 在检查通过后打印一段明确命令”
Codex 更新
.githooks/pre-push：先执行 scripts/pr-ready.sh，通过后打印一段可复制给 Codex 的 PR gate 指令，要求从 code-reviewer、security-auditor、test-engineer 三个视角输出 GO/NO-GO。结果 / 影响：普通 terminal push 后有明确提醒，但这仍然只是提示，不会自动激活当前 Codex 会话中的 review。
“但是你把三个 review 的要求打印到 pr 里，也没有办法激活呀？”
Codex 承认问题：把要求打印到 hook 或 PR 模板里不会自动激活 AI review。真正自动化有两条路：当前 Codex 会话里显式触发，或 GitHub Action 里另起 API-backed reviewer bot。
结果 / 影响：团队意识到“提醒”和“执行”是两层。仅靠文案不能完成 PR gate，必须选择一个能触发 Codex 的机制。
“或者可不可以加到 codex 的 hook 功能上呢”
Codex 检查本机配置，发现全局
~/.codex/config.toml 中 codex_hooks 与 multi_agent 已开启过，且存在 ~/.codex/hooks.json。初步判断 Codex hook 更接近目标，但需要项目级配置而非全局污染。结果 / 影响：方向从 Git hook 转向 Codex hook：目标不是在 shell 里强行跑 AI，而是在 Codex 工具执行后给当前会话注入上下文。
“仓库里没有 .codex/hooks.json，是不是自己创建就可以，你需要搜下官方文档和 repo 来找到 更好的方案”
Codex 查官方文档，确认 Codex 支持 repo-local
<repo>/.codex/hooks.json 与 <repo>/.codex/config.toml，前提是项目被 trusted。随后创建项目级 hook：在 Codex 执行 StoryCam git push 后注入 PR gate 提醒。结果 / 影响：StoryCam 有了项目级 Codex hook 的第一版实现，避免依赖全局 hook；同时文档更新，说明这不是 CI，也不是自动 AI review。
“现在关了 codex 的 hooks 设置，但这样就没有办法在 pr 的前自动走 pr gate，看看有什么更好的方案？”
Codex 提出 GitHub Action 方案：在 PR opened / synchronize 时运行
openai/codex-action，将 review 结果评论到 PR。方案能自动化，但需要 OPENAI_API_KEY secret，并且变成另一套 CI bot 流程。结果 / 影响：短暂形成 GitHub AI PR Gate 草案，但用户随后判断这种 Action “不太合理”，不希望把 StoryCam 的 PR gate 变成另一个外部 CI reviewer。
“这种 action 也不太合理，还是设置在 codex 的 hooks 能更好，但要找好时机，整理再设计下”
Codex 进入方案整理：确认最佳触发时机是 Codex 成功执行
git push 后；触发后不要自动跑三路 review，而是先询问用户。用户进一步确认：撤掉 GitHub Action，保留 Git pre-push 的确定性检查。结果 / 影响：决策收敛为“Codex hook + ask-before-run”。GitHub Action 不再是主线；AI review 保持在当前 Codex 会话中，由用户确认启动。
“PLEASE IMPLEMENT THIS PLAN...”
Codex 实施计划：撤掉 GitHub AI action 路径，启用
.codex/config.toml 中的 codex_hooks = true，更新 hook 脚本，让它只在 StoryCam 内的成功 git push 后提醒，并用 .git/storycam-pr-gate-reminder-head 对同一 HEAD 去重。结果 / 影响：StoryCam 回到项目级 Codex hook 方案。实现后跑了 JSON/TOML/Python 编译与多种 hook 输入模拟，确认成功 push 才会提示，失败 push、非 StoryCam cwd、非 push 命令都会静默。
“我看这个 hooks 是在工具执行之后，但这样就会在任何涉及工具操作后都执行这个，是不是有问题？”
Codex 解释当前
PostToolUse + matcher * 的问题：功能上能过滤，但每次工具调用都会 fork 脚本，不够精准，调试也更吵。建议至少缩小到 shell 工具。结果 / 影响：用户继续推进精度问题，指出匹配 Bash 依然会对所有 Bash 命令执行，要求更精准的方法。
“但去匹配 bash 依然会有这个问题，只是缩小了范围，bash 也不一定都是 push 动作，有没有更精准的方法”
Codex 设计两阶段握手：
PreToolUse(Bash) 只在命令是 git push 时记录 tool_use_id；PostToolUse(Bash) 只处理同一个 tool_use_id 的结果。这样普通 rg、pnpm、git status 不会进入完整 PR gate 逻辑。结果 / 影响：最终实现从“所有工具后过滤”升级为“只追踪一次具体 push 调用”。这是本 session 最关键的工程收口。
关键时刻
1. Git hook 没生效的根因
问题：仓库里已有 .githooks/pre-push，但提交/推送时用户没有看到预期流程。
为什么重要：这暴露了“流程文档存在”和“本地 Git 实际执行”之间的断层。
处理：启用 git config core.hooksPath .githooks，并明确它是 pre-push，不是 pre-commit。
2. AI review 不放进 Git hook 自动阻塞
问题：是否每次 PR 前自动唤起 code-reviewer + security-auditor + test-engineer。
为什么重要：AI review 慢、依赖上下文与模型，不适合成为本地 Git hook 的机械阻塞项。
处理：确定性检查自动跑，AI PR gate 由 Codex 会话询问后运行。
3. GitHub Action 方案被降级
问题：GitHub Action 可以自动跑 Codex review，但需要独立 API key，并把 review 变成外部 CI bot。
为什么重要：StoryCam 当前更需要贴近开发会话的协作流程，而不是多一套可能重复的 PR 评论机器人。
处理：撤掉 GitHub AI PR Gate，保留普通 CI，把智能审查触发放回项目级 Codex hooks。
4. 从 PostToolUse 泛匹配到两阶段握手
问题：PostToolUse + * 或只匹配 Bash 都会让 hook 在太多工具调用后执行。
为什么重要：PR gate 触发应当精准、安静、可解释，否则 hook 会成为隐性噪音。
处理：PreToolUse 记录具体 git push 的 tool_use_id，PostToolUse 只处理同一调用的成功结果。
工程证据
分支与默认分支
- Branch:
dev - Remote:
origin/dev - GitHub default branch:
dev - PR / Commit: 本 session 未创建 PR 或 commit。
本地 Git Hook
- 配置：
core.hooksPath = .githooks - 入口：
.githooks/pre-push - 脚本：
scripts/pr-ready.sh - 检查：
pnpm lint、pnpm typecheck、pnpm test、pnpm build
Codex Hook 文件
.codex/config.toml: 启用codex_hooks = true.codex/hooks.json: 配置PreToolUse与PostToolUse.codex/hooks/storycam_pr_gate_reminder.py: 负责 push 识别、结果判断、HEAD 去重与上下文注入AGENTS.md、docs/PR_REVIEW.md: 更新协作规则与流程说明
撤销的方案
- 删除 GitHub Codex Action 路径：
.github/workflows/codex-pr-gate.yml - 删除 GitHub review prompt：
.github/prompts/storycam-pr-gate.md - 保留普通 CI：
.github/workflows/ci.yml
验证结果
- 通过：
.codex/hooks.jsonJSON 解析 - 通过：
.codex/config.tomlTOML 解析 - 通过：hook Python 脚本编译
- 通过：模拟 Pre/Post 两阶段 hook 场景
- 未执行：真实 Codex 发起的测试分支 push 验收，待后续实际流程中确认。
敏感信息处理
- 本 session 曾读取本机 Codex 配置与 hook 配置。
- 任何 token、API key、secret、签名 URL 均不在本叙事中展开，统一视为
[REDACTED]。 - 无 provider 原始 payload、用户私密素材或 cookie 被记录。
最终 hook 逻辑摘要：
PreToolUse(Bash)
- 如果命令不是 git push：退出
- 如果是 git push：记录 tool_use_id 到 .git/storycam-pr-gate-pending.json
PostToolUse(Bash)
- 如果 tool_use_id 不匹配 pending：退出
- 如果 push 失败：清理 pending 并退出
- 如果 push 成功：按 HEAD 去重
- 注入 additionalContext，让 Codex 询问是否运行 StoryCam PR gate对外讲解用总结
这一章展示的是 StoryCam 项目如何把“代码质量检查”和“AI 协作审查”分层。我们先把默认开发分支统一到 dev，再修复本地 Git hook 没有真正启用的问题。随后围绕 PR Gate 反复讨论：哪些检查应该自动、哪些判断必须由 Codex 在当前上下文里完成、哪些自动化会带来不必要的成本和噪音。
最终，StoryCam 没有选择把 AI reviewer 塞进 Git hook，也没有把它外包给 GitHub Action bot，而是采用项目级 Codex hook：当 Codex 自己完成一次成功的 git push 后，它会被提醒询问是否运行三视角 PR gate。这个设计保留了人对 AI review 的确认权，同时让关键时机不再完全依赖记忆。
这一步连接了前面的开发规范建设和后续的发布流程：确定性检查继续由本地 hook 与 CI 执行，复杂的安全、架构、测试覆盖判断则由 Codex 在合适时机进入协作模式。